home *** CD-ROM | disk | FTP | other *** search
/ New Star Software Collection / NSS_Collection.iso / 3-170 dbase 10 for windows / 1.ima / DOC.PAK / XBUILDER.TXT < prev   
Text File  |  1993-07-26  |  14KB  |  379 lines
  1. Copyright (c) 1991-1993 Borland International, Inc.  All Rights Reserved.
  2.  
  3.                   THE EXPRESSION BUILDER
  4.                   ----------------------
  5.  
  6. Use the Expression Builder to build valid dBASE expressions and 
  7. insert them into the text editor, the Command window, and certain 
  8. dialog box fields. 
  9.  
  10. Contents
  11. --------
  12.  
  13. I.    What the Expression Builder does
  14. II.   How to display the Expression Builder
  15. III.  The GETEXPR() function
  16. IV.   About the Expression window and the Safety Net mode
  17. V.    Building expressions using the Category, Type, and Paste list boxes
  18. VI.   How to paste an element into the Expression window
  19. VII.  Specifying a result type
  20. VIII. About the Safety Net
  21. IX.   Editing constants
  22. X.    Using Undo and Group
  23. XI.   Keyboard Quick Reference
  24. XII.  Using the DBASEWIN.FNF table to modify the list of functions
  25.  
  26.  
  27. What the Expression Builder does
  28. --------------------------------
  29.  
  30. The Expression Builder only builds expressions. It does not assign 
  31. anything.
  32.  
  33. When you build an expression in the Expression Builder and then 
  34. click the OK button, the expression is inserted into the environment 
  35. from which you called the Expression Builder.
  36.  
  37. How to display the Expression Builder
  38. -------------------------------------
  39.  
  40. There are four ways to display the Expression Builder:
  41.  
  42. -  Use the GETEXPR() function in the Command window or in a program.
  43.  
  44. -  Press the Expression Builder button (currently, the rightmost button) 
  45.    on the SpeedBar. 
  46.    
  47. -  Select Build Expression from the Edit menu.
  48.  
  49. -  Press Ctrl+E.
  50.  
  51. If any text is selected in the Command window or in the text 
  52. editor when you call the Expression builder, that text will appear 
  53. in the Expression window as the default expression to be edited.
  54.  
  55. You can also use the Expression Builder when you are in FOR() 
  56. or WHILE() fields in certain dialog boxes. 
  57.  
  58.  
  59. The GETEXPR() function
  60. ----------------------
  61.  
  62. The syntax of GETEXPR() is as follows:
  63.  
  64.    GETEXPR( [ <expC1>  [ , <expC2>  [ , <expC3> ] ] ] )
  65.  
  66. where: 
  67.  
  68. <expC1> is a string that will appear in the Expression window as the 
  69. default expression to be edited.
  70.  
  71. <expC2> is a string that appears as the title on the Expression 
  72. Builder title bar
  73.  
  74. <expC3> is the desired result type. This result type appears in the 
  75. Result Type list box in the Expression Builder. <expC3> can be 
  76. "C", "N", "L", "D", or "X". The "X" means 'Any' result type. The 
  77. default is "X".
  78.  
  79. Examples:
  80.  
  81.    GETEXPR()
  82.    X = GETEXPR()         
  83.    X = GETEXPR("","Create a Filter Expression","L")
  84.    X = GETEXPR(X)
  85.  
  86. About the Expression window and the Safety Net mode
  87. ---------------------------------------------------
  88.  
  89. You build expressions in the Expression Builder's Expression window. 
  90. There are two modes available:
  91.  
  92. -  With the Safety Net on, you select valid elements from a list 
  93.    and paste them into the Expression window. 
  94.  
  95. -  With the Safety Net off, you can select and paste elements, as 
  96.    above, but you can also type expressions directly into the 
  97.    Expression window. 
  98.  
  99. In either case, the Expression Builder does not let you insert the 
  100. expression into the calling environment unless the expression is 
  101. valid.
  102.  
  103. To toggle the Safety Net on and off, check and uncheck the Safety 
  104. Net check box at the top of the Expression Builder. 
  105.  
  106. Building expressions using the Category, Type, and Paste list boxes
  107. -------------------------------------------------------------------
  108.  
  109. Use the three list boxes in the lower half of the Expression Builder 
  110. to display valid items that can be used to build an expression. 
  111.  
  112. The items in the leftmost box are the most general, and those in the 
  113. rightmost list box are the most specific.
  114.  
  115. Move from left to right, selecting which items to show, and then 
  116. choose an item from the rightmost list box (the Paste list box) to 
  117. paste into the Expression window. 
  118.  
  119. The three list boxes are explained below:
  120.  
  121. -  The Category list box lists the main categories of items you can 
  122.    use to create an expression. These categories are "Constant," 
  123.    "Field," "Function," "Operator," and "Variable."
  124.  
  125. -  The Type/Table list box shows subcategories of whatever category 
  126.    is selected in the Category list box. (When you choose "Field" from 
  127.    the Category list box, the Type/Table list box displays a list of 
  128.    all open tables.)
  129.  
  130. -  The Paste list box shows all the elements that are named by the 
  131.    subcategory selected in the Type/Table list box. 
  132.  
  133. Some possible combinations are as follows:
  134.  
  135. If you select this     And then select this     These items appear
  136. item from the          item from the Type/      in the Paste list
  137. Category list box...   Table list box...        box...
  138. --------------------   ----------------------   ---------------------
  139.  
  140. "Function"             "Data type conversion"   All the dBASE 
  141.                                                 functions that can be 
  142.                                                 used for converting 
  143.                                                 data types 
  144.  
  145. "Field"                a table name             All the fields in the
  146.                                                 selected table
  147.  
  148. "Variable"             "User"                   All the user-defined
  149.                                                 variables currently  
  150.                                                 in memory             
  151.  
  152. How to paste an element into the Expression window
  153. --------------------------------------------------
  154.  
  155. To paste an element from the Paste list box into the Expression window, 
  156. do one of the following:
  157.  
  158. -  Using the mouse,
  159.  
  160.    -  Double-click the desired item in the Paste list box, or
  161.  
  162.    -  Drag the desired item from the Paste list box to the Expression 
  163.       window
  164.  
  165. -  Using the keyboard
  166.  
  167.    1. Select an item from the Paste list box (either by clicking once 
  168.       with the mouse or by navigating to the item with the keyboard), 
  169.       then
  170.  
  171.    2. Press the Space bar
  172.  
  173. The item is pasted into the Expression window at the cursor position 
  174. in the window.
  175.  
  176. When the Safety Net is off, you can use standard Windows key combinations 
  177. to cut, copy, and paste text in the Expression window. For example, 
  178. Ctrl+X cuts text, Ctrl+C copies text to the clipboard, and Ctrl+V 
  179. inserts text from the clipboard.
  180.  
  181. Specifying a result type
  182. ------------------------
  183.  
  184. By default, the Expression Builder accepts any data type for the result 
  185. of an expression. However, you can specify what data type the expression 
  186. must evaluate to, in order to be considered valid. 
  187.  
  188. Choose a data type from the Result Type list. The options are "Any," 
  189. "Character," "Date," "Logical," and "Numeric." If you choose any of 
  190. these choices other than "Any," the expression must evaluate to the 
  191. selected data type in order to be valid. If the result is the wrong 
  192. data type, the message "Wrong result type..." is displayed in the 
  193. information box (located below the three list boxes), and the OK button 
  194. is dimmed.
  195.  
  196.  
  197. About the Safety Net
  198. --------------------
  199.  
  200. When the Safety Net is on (i.e., when the Safety Net check box is 
  201. checked):
  202.  
  203. -  You must select items from the Paste list box and paste them into the 
  204.    Expression window. That is the only way to insert items into the 
  205.    expression. You cannot type elements directly into the Expression 
  206.    window when the Safety Net is on, except for constants--see below under 
  207.    "Editing Constants."
  208.  
  209. -  Bladerunner tries to validate the expression every time you insert a new 
  210.    item. If the expression is valid, the result of the expression is shown 
  211.    in the information box directly below the Expression window. If the 
  212.    expression is invalid, a message explaining the problem is displayed, 
  213.    and the OK button is dimmed. This always happens when you insert a token 
  214.    that must be replaced with a valid operator or operand.
  215.  
  216. -  Colored placeholder elements, or "tokens," are inserted to show elements 
  217.    missing from your expression. A white "Op" means you must insert an 
  218.    operator. A yellow text string means you must insert an operand. The 
  219.    text string tells you what kind of operand is required.
  220.  
  221. -  The cursor in the Expression window is between elements, never within 
  222.    an element.
  223.  
  224. When the Safety Net is off:
  225.  
  226. -  You can type directly into the Expression window. 
  227.  
  228. -  The Expression Builder does not try to validate your expression until 
  229.    you choose the OK button. If the expression is invalid, the OK button is 
  230.    dimmed so you cannot insert the invalid expression into the calling 
  231.    environment. 
  232.  
  233. -  The result of the expression that you are building is not shown in the 
  234.    information box. If you are working with the Safety Net off and you want 
  235.    to see the result of the expression without leaving the Expression 
  236.    Builder, turn the Safety Net on. The expression will be evaluated and the 
  237.    result shown in the information box.
  238.  
  239. You can only turn Safety Net on or off if the expression is valid. The 
  240. information box below the expression tells you the state of your expression.
  241.  
  242. Editing constants
  243. -----------------
  244.  
  245. When the Safety Net is on, you can type constants directly into the 
  246. Expression window. This is the only time you can type directly into the 
  247. Expression window when you are in Safety Net mode. 
  248.  
  249. To type a constant into the Expression window when the Safety Net is on, 
  250. you first must insert a constant. Follow these directions: 
  251.  
  252. 1. Select "Constant" from the Category list box.
  253.  
  254. 2. Select a type of constant from the Type/Table list box.
  255.  
  256. 3. Choose a constant from the Paste list box by double-clicking it, 
  257.    dragging it into the Expression window, or by selecting (highlighting) 
  258.    it and then pressing the space bar.
  259.  
  260. 4. Then either
  261.  
  262.    -  Put the cursor next to the constant in the Expression window and 
  263.       start typing, or
  264.  
  265.    -  Right-click the mouse near the constant in the Expression window. 
  266.  
  267.    In either case, a text box appears where you can type (or finish 
  268.    typing) the constant.
  269.    
  270. 5. Press the Tab key or the Enter key to finish.
  271.  
  272. You cannot insert illegal characters for the constants, e.g., you can't 
  273. insert a character for a numeric constant.
  274.  
  275. Using Undo and Group
  276. --------------------
  277.  
  278. Click the Undo button (in the upper-right corner) to undo the last 
  279. operation. To group items in the Expression window, i.e., to put 
  280. parentheses around them, highlight the items and click the Group 
  281. button (in the upper-right corner).
  282.  
  283. Keyboard Quick Reference
  284. ------------------------
  285.  
  286. These keystrokes work the same whether the Safety Net is on or off, 
  287. with the exception of the Left and Right arrows, as noted below:
  288.  
  289. Home         Move cursor to end of line
  290.  
  291. End          Move cursor to beginning of line
  292.  
  293. PgUp         Move cursor up multiple lines 
  294.  
  295. PgDown       Move cursor down multiple lines
  296.  
  297. Up Arrow     Move cursor up one line
  298.  
  299. Down Arrow   Move cursor down one line
  300.  
  301. Left Arrow   Move cursor left one expression element: 
  302.              one character when Safety Net is off, or one token 
  303.              when Safety Net is on
  304.  
  305. Right Arrow  Move cursor right one expression element: 
  306.              one character when Safety Net is off, or one token 
  307.              when Safety Net is on
  308.  
  309. Ctrl + Home  Move cursor to beginning of expression
  310.  
  311. Ctrl + End   Move cursor to end of expression
  312.  
  313. The Shift key causes any of the above keystrokes to extend the 
  314. current selection.
  315.  
  316. Using the DBASEWIN.FNF table to modify the list of functions
  317. ------------------------------------------------------------
  318.  
  319. Information about the functions that are displayed in the Paste 
  320. list box and that can be pasted into the Expression window is 
  321. stored in a table called DBASEWIN.FNF. 
  322.  
  323. You can add records to this table to add your own 
  324. user-defined functions (UDFs) to the Expression Builder.
  325.  
  326. DBASEWIN.FNF contains the following required fields. 
  327.  
  328. Field
  329. Name       Description
  330. -----      ------------------------------------------
  331.  
  332. NAME       Name of the function, e.g., TAGCOUNT.
  333.  
  334. NAME_EXT   One or more dots (periods) to indicate that there is one 
  335.            or more possible versions of this function, depending 
  336.            on which arguments are used. For example, TAGCOUNT appears 
  337.            in the NAME field in two records. The first record has 
  338.            one dot in the NAME_EXT field, and the second record has 
  339.            two dots in the NAME_EXT field. When the first version is 
  340.            chosen in the Paste list box, the following form of the 
  341.            function is pasted:  
  342.            
  343.            TAGCOUNT(.mdx filename)
  344.            
  345.            When the second version is chosen, the following form of 
  346.            the function is pasted: 
  347.            
  348.            TAGCOUNT(.mdx filename, database alias)
  349.            
  350.            The arguments are taken from the ARGUMENTS field (see
  351.            below).
  352.  
  353. ARGUMENTS  Comma-delimited list of arguments for the function named in 
  354.            the NAME field. (See also the explanation for the 
  355.            NAME_EXT field.)
  356.  
  357. CATEGORIES Comma-delimited list of language element types that are 
  358.            displayed in the Type list box.
  359.  
  360. PURPOSE    The purpose of the function. 
  361.            
  362. USERHELP   (To be added later.)
  363.  
  364. The field names listed above cannot be changed. Other fields can be 
  365. added, but they are ignored by the Expression Builder. All fields
  366. are character data type. The size of the fields can be changed.
  367.  
  368. When you highlight a function in the Paste list box of the Expression
  369. Builder, information from the DBASEWIN.FNF table is displayed in the 
  370. information box, as explained below:
  371.  
  372. First line: This text is constructed from 1) the name in the 
  373. NAME field, 2) open parenthesis, 3) the arguments from the 
  374. ARGUMENTS field, 4) close parenthesis.
  375.  
  376. Second line: the text from the PURPOSE field.
  377.  
  378.  
  379.